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1.0  IDENTIFICATION 

1.1  Title 

Unpacking  and  Packing  of  Binary  Data 

1 . 2 Identification  Name 
M2 - NRL -THREEBIT 

1 . 3 Classification  Code 

M2  - Data  Handling,  Conversion  and/or  Scaling 

1.4  RCC  Identification  Number 
M 2002000 

1 • 5 Entry  Points 

THREEBIT,  UNPACK,  PACK 

1 . 6 Programming  Language 

Language:  3600/3800  F0RTRAN 
Routine  Type:  Subroutine 

Operating  System:  DRUM  SC0PE  2.1 

1 . 7 Computer  and  Configuration 
CDC  3800 

1 . 8 Contributor  or  Programmer 

Gary  W.  Phillips,  Code  6603M,  Consultant  Staff, 
Nuclear  Sciences  Division 

1 . 9 Contributing  Organization 

NRL  - Naval  Research  Laboratory, 

Washington,  D.  C.  20375 

1.10  Program  Availability 

1.10.1  Submittal:  Program  write-up,  Fortran 

source  deck,  source  listing 

1.10.2  On  File:  RCC  Program  Library 
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1.11  Verification 


The  routine  has  been  successfully  tested  in 
packing  and  unpacking  binary  data  in  bytes 
of  length  3,  6,  . ..,  48  bits.  In  addition 
it  has  been  used  extensively  to  unpack  data 
read  in  from  7- track  tapes  in  binary  format 
with  9,  12,  15  and  24  bit  bytes. 

1 .12  Date 

1 July  1974 

2 . 0  PURPOSE 


2 . 1 Description  of  the  Routine 

This  is  a general  purpose  routine  to  unpack 
data  stored  in  core  in  packed  binary  format 
or  to  pack  binary  data  stored  word  for  word 
in  an  array.  The  data  must  be  stored  in 
* bytes  which  are  a multiple  of  three  bits  in 
length  with  a minimum  length  of  3 bits  and  a 
maximum  of  48  bits. 

It  is  useful  for  unpacking  data  read  in  packed 
binary  form  and  sorting  it  into  an  array  so  as 
to  be  convenient  for  further  processing  by  a 
Fortran  program,  or  for  preparing  data  from  an 
array  for  writing  out  in  a compact  form,  or 
possibly  for  intermediate  storage  of  large 
arrays  during  execution  of  a program  in  order 
to  save  core  space. 

2 . 2 Problem  Background 

The  program  was  originally  written  to  unpack 
data  read  in  from  7-track  tapes  in  packed  binary 
format  of  9,  12,  15,  and  24  bits  in  length.  An 
existing  program  in  the  RCC  Library,  M2  UCSD  BYTES, 
was  found  to  be  inapplicable  as  it  could  pack  and 
unpack  bytes  in  lengths  only  of  1,  6,  12,  and 
24  bits.  Thus  it  could  not  be  used  for  9 bit  and* 
15  bit  lengths.  Also,  the  logic  was  set  up  to 
handle  only  one  byte  at  a time  rather  than  handling 
the  data  as  an  array. 
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3.0  USAGE 

3. 1 Calling  Sequence  or  Operational  Procedure 

UNPACK  (NA , ARRAY , NT , TEMPLATE , NW , IW0RK , NB I TS , NRETRN) 
PACK  (NA , ARRAY , NT , TEMPLATE , NW , I W0RK , NB I TS , NRETRN ) 

3 . 2 Arguments,  Parameters,  and/or  Initial  Conditions 

Entry  UNPACK  calls  for  unpacking  data  from  ARRAY 
into  TEMPLATE . 

Entry  PACK  calls  for  packing  data  from  TEMPLATE 
into  ARRAY. 

NA  is  the  dimension  of  ARRAY. 

ARRAY  is  the  array  used  for  the  packed  data. 

NT  is  the  dimension  of  TEMPLATE. 

TEMPLATE  is  the  array  used  for  the  unpacked  data. 

NW  is  the  dimension  of  IW0RK  and  must  be  at 
least  2*NA. 

IW0RK  is  working  space  used  by  the  routine. 

NBITS  is  the  length  in  bits  of  the  bytes. 

NRETRN  is  a parameter  returned  by  the  routine 
to  indicate  the  length  of  the  unpacked  or 
packed  data  returned.  If  negative,  it 
indicates  an  error  condition  (see  Section  3.5). 

3 . 3 Space  Required  (Decimal  and  Octal) 

3.3.1  Unique  Storage: 

777  octal  (511  decimal)  locations 
exclusive  of  comp- -ter  system  library 
functions 

3.3.2  Common  Blocks:  None 

3.3.3  Temporary  Storage:  IW0RK(NW) 


3.4  Messages  and  Instructions  to  the  Operator 
None 

3 . 5 Error  Returns,  Messages,  and  Codes 

Several  error  messages  are  printed  on  the  standard 
output  unit.  A negative  value  for  NRETRN  indicates 
the  data  was  not  processed  and  the  reason  is 
printed. 

a.  NBITS  = (13)  IS  N0T  AN  INTEGER  MULTIPLE  0F  3 

Data  not  processed,  NBITS  must  be  evenly 
devisible  by  3,  NRETRN  = -1. 

b.  NBITS  = (13)  IS  GREATER  THAN  48 

Data  not  processed,  NBITS  cannot  exceed  48, 
NRETRN  = -2. 

c.  NW  = (15)  MUST  BE  AT  LEAST  TWICE  NA  = (15) 

Data  not  processed,  NW  is  less  than  2*NA, 

NRETRN  = -3. 

The  calling  program  should  take  appropriate  action 
. when  a negative  NRETRN  is  received,  e.g.  terminate 
the  program  or  go  on  to  process  the  next  data  set. 

3 . 6 Informative  Messages  to  the  User 

The  following  messages  indicate  only  part  of  the  data 
could  be  processed. 

a.  NUMBER  0F  BYTES  = (15)  EXCEEDS  NT  = (15) 

NT  BYTES  WILL  BE  PROCESSED 

ARRAY  could  not  be  completely  unpacked 
because  NT  was  less  than  (NA*48)/NBITS, 
the  total  number  of  bytes  of  length  NBITS 
contained  in  ARRAY. 

b.  PACKED  LENGTH  = (110)  EXCEEDS  NA  = (15) 

THE  FIRST  (15)  BYTES  WILL  BE  PROCESSED 

NT  bytes  of  length  NBITS  would  occupy 
a packed  length  of  (NT*NBITS+47) / 4 8 
words,  which  exceeds  NA.  Only  (NA*48) /NBITS 
bytes  will  be  packed. 

Upon  return  from  the  above  two  cases  or  upon  a normal 
return  from  a cal]  to  UNPACK  or  PACK,  NRETRN  will 
contain  the  length  in  words  of  the  unpacked  (TEMPLATE) 
or  packed  (ARRAY)  data,  respectively.  Partial  bytes 
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will  not  be  processed.  If  the  packed  data  ends 
with  a partial  word  it  will  be  zero  filled  on 
the  right.  Elements  of  TEMPLATE  or  ARRAY  with 
index  greater  than  NRETRN  will  contain  their 
previous  values.  Consequently,  after  return 
from  THREEBIT  the  calling  program  should  take 
care  not  to  process  elements  of  the  data  with 
index  greater  than  NRETRN. 

3 . 7 Input 
None 

3 . 8 Output 

None  other  than  the  output  described  in  Sections 
3 . 5 and  3.6. 

3 . 9 Formats 

Not  applicable 

3.10  External  Routines  and  Symbols 
XM0DF 

3. H Timing 

No  timing  estimates  were  made;  the  timing  depends 
on  the  data  length  and  byte  length.  The  example 
in  Section  7.0  took  five  seconds,  excluding 
compilation  time. 

3.12  Accuracy 

Not  applicable 

3.13  Cautions  to  Users 

See  Sections  3.5  and  3.6 
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3. 14  Program  Deck  Structure 


gJ0B  card 
gFTN  card 

main  program  deck  (includes  call  to  PACK  or  UNPACK) 
SUBR0UTINE  THREEBIT 
SC0PE  card 


pL0AD  card 

gRUN  card 

Data  (if  any) 

E0F 

3 *.  1 5 References  - Literature  - Appendices 
None 

4.0  METHOD  OR  ALGORITHM 


The  Fortran  statements  DEC0DF,  and  ENC0DE  are  used  in 
UNPACK  to  go  from  a packed  binary  format  in  ARRAY  to  a 
packed  BCD  format  in  IW0RK  to  an  unpacked  one  byte  per 
word  format  in  TEMPLATE.  For  entry  PACK  the  reverse  of 
the  above  is  done.  Variable  formats  and  variable 
dimensions  are  used  to  make  the  routine  as  general  as 
possible . 
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5.0  SOURCE  LANGUAGE  LISTING 

subroutine  threebitin».ark*y,nt.templ*te.n«.i.09<.nbits.nretrn) 

l mil  or  ».n«v  o.t. 

c IDENT  NAME  - M2  NRL  ThREEBIT 
C LANGUAGE  - 3600/3800  FORTRAN 
r COMPUTER  • COC  3800  . . 

r CONTRIBUTOR  - GARY  W*  PHILLIPS*  CODE  6603 
r CONSULTANT  staff 

r NUCLEAR  SCIENCES  DIVISION 

c ORGANIZATION  - NAVAL  RESEARCH  LABORATORY 
C WASHINGTON,  d.C.  20375 

C OATE  - l*  JUNE  197* 

C GENERAL  PJRPOSE  PROGRAM  TmREE^BITS^IN^LENGTmI^UP^TO*?*  BlTS^AXlMUM. 
C KtS!  UNPACK  OPERATES  0-ACKEO  UATA  IN  ARRAY  OIMENSTON  NA.  ANO 

C RETURNS  Ut  UNPACKED  DATA  ^nLE?l«^TE  l3t3  ISSa!. 

‘ r;5lKP:S?A-Iitip3‘5Ks  ^I«CO  OF  dimension  N-  at  LEAST  TWICE  NA. 

C DIMENSION  ARRAY (NA) • TEMPLATE (NT) * IWORK (NW) • IF0HMI2) » JFORM (2> 

type  integer  array *templ*te 

c 

ENTRY  JNPACK 
NP ACK*  0 
GO  TO  10 
C 

ENTRY  RACK 
NP ACK* 1 

C 10  IF (M0D1NBITS,3) 1 20*30 

!5  is  -»I  - !«£•*“  »*■»>•«  ot 

NR£TON«»l 

return 

c 

30  KsNR I T S/3 

IF (NRITS.LT.4R)  GO  TO  *0 

31  EM5m  »•* is  ih»*  ***' 

nre  trn«-2 

RF TURN 

C 40  IF  (NA._E.N*/?)  GO  TO  SO 

4i  yasiTtiar-tN.  «usT  »t  least  t-ke  n*  ••«» 

nRETRN«»3 

return 

C 

50  IF(NRACK)  GO  TO  RO 
NBr ( NA»48) /N3ITS 

IF (NR. „E «NT > GO  TO  100 

51  33w-IT?1oSuJ»BER  of  BYTES  -MS*  EXCEEDS  NT  -IS/ 

• • nT  3 Y T £ S -IuL  t?C  PROCFSScD*) 
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NB»NT 

570 

00  TO  100 

500 

500 

#•0 

NB*NT 

600 

NC*(N0*NBITS*471/4B 

610 

IF(NC.LE.NA)  60  TO  100 

620 

NHa(M**4H)/N91TS 

610 

PRI  *T  61»NC,NA,n8 

640 

61 

FORMAT (*0P*CKEO  LENGTH  «*I10*  EXCEEDS  NA  **15/ 

650 

• • The  FIRST*I5*  BYTES  BILL  BE  PROCESSED*! 

660 

NC*(NH*NBITS*471/48 

670 

6B0 

100 

IF<NA-?S6)  110*110*120 

690 

110 

lML*l**NA 

700 

tNCOOE (16*101  * JFORM)  NA 

710 

101 

FORMAT (*<*14*0 1*1*) 

720 

GO  TO  130 

730 

120.  I4*NA/256 

740 

IF (M00(NA*256) 1 IA«IA*l 

750 

ImL*IA»4096 

760 

ENCODE  <16*121 » JF0RR1  U 

770 

1?1 

FORMAT  (•  (*I2* (2S601  n*> 

7M0 

130 

IF (N9-2S61  1*0,140*1- 

790 

1*0 

IMB*NM*K 

BOO 

ENCODE <16, 141* IF OR Ml  NR*  K 

RIO 

1*1 

FORMAT (*t*I4*0*I 2*1*1 

R20 

: 

GO  To  200 

010 

150 

I0«N0/?56 

040 

IF (M00(NR«?56) 1 10*10*1 

050 

Imh«TR*?56*K 

060 

ENCODE <16.151 .IFOHMl  Ir*k 

870 

151 

FORMAT <•<• 12* <2560* 12*)  1*1 

8A0 

800 

200 

IF(NPACK)  240*210 

900 

210 

ENCODE  < I «L» JFORM.I^ORA) (ARRAY ( 11  * I«1*NA) 

910 

220 

DECODE  < I MB* I FORM, I MONK)  (TEMPLATE  III • 1*1 «NR1 

920 

NHETPN«NB 

930 

RETURN 

940 

960 

2*0 

NJ*2*NC 

940 

IMORK(MJ)*0 

970 

?*S 

ENCODE  < Imh*  I FORM,  ImORK)  (TEMPUATFU)  ,1*1,N«i 

980 

250 

DECOOE  < I «L  * JFORM* 1 MORM (ARRAY < I ) , l«i ,NC1 

990 

NHETRN«NC 

1000 

1010 

ENO 

1020 
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6.0  COMPARISON 


The  present  routine  will  handle  packed  arrays  with  byte 
lengths  of  any  multiple  of  three  bits  up  to  48  bits. 

The  routine  M2  UCSD  BYTES  in  the  RCC  Program  Library  will 
handle  byte  lengths  of  1,  6,  12,  and  24  bits,  but  only 
one  byte  at  a time. 

Except  for  the  one  bit  case,  it  is  usually  preferable  to 
unpack  the  data  before  further  processing  rather  than 
handling  it  byte  by  byte. 

7.0  TEST  METHOD  AND  RESULTS 

A test  program,  PCKUNPCK,  was  written  to  unpack  from 
ARRAY  to  TEMPLATE  and  then  pack  from  TEMPLATE  into  ARRAY , 
for  NBITS  equal  to  6,  18,  and  30.  The  listing  of 
PCKUNPCK  and  the  results  follow. 
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PROGRAM  PCKUNPCK 

DIMENSION  ARRAY (4) »1RRaY(A) ♦TEMPLATE (20) • IMORK <8> 
OATA  (ARRAY«4<l234’67(Jl23A56708I  I • 

• (NAM) ♦ (NT«20> • <N*«8) ♦ (NAM) 

type  integer  array, array, template 

DO  20  I«6,30#12 
NHITS«I 
NCHAR*V8I TS/3 
PRINT  IOI.NmITS.NCHAR 

101  FORMAT!//*  - - - - NBITS  «*I4*  NCMAR  **I3* 

PRINT  lOt  ARRAY 

10  FORMAT (*f ARRAY*/1X4( !X0l6> > 

UO  11"  J«1,NT 

no  template«j)»o 

CALL  UNP*CM(NA#ARPAT»NT*TEMPLiTc#MMf|MOPK«NHlTS.NLl 

print  1 1 «nl* (Template ( j) • j*i«nli 

11  FORMAT  (*<*TEMPLATE  LENoTh  *•  1 3/(lX*(JX0161  ) ) 

. DO  12  J«1,NA 

12  rtHMAY ( J) *0 

CALL  P ACK  (NAi ARRAY ♦NT.TEMPLATEfNMMMORKtNHtTStNL) 

20  PRINT  13,NL* (ARRAY ( J) ♦ J* 1 »NL) 

13  FORMAT (*0RRRAY  LENGTH  ■« 1 3/1X4 ( 1X0161) 

ENO 
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N8 ITS  « 6 NCHAR  . 2 


ARRAY 

123*567012345670  123*5670123*5670  123*5670123*5670  123*5670123*5670 
NUMBER  OF  BYTES  « 32  EXCEEOS  NT  » 20 

NT  bTTES  -ILL  be  processed 

TEMPLATE  LENGTH  ■ 20 

0000000000000012  000000000000003*  0000000000000056  0000000000000070 
0000000000000012  000000000000003*  00n0000000000056  0000000000000070 
0000000000000012  000000000000003*  0000000000000056  0000000000000070 
0000000000000012  000000000000001*  00o0000000000056  ooooooooooooooTo 

0000000000000012  000000000000003*  0000000000000056  OOOOOOOOOOOOOOTO 
. BRRAY  length  » 3 

123*5670123*5670  123*5670123*5670  123*567000000000 


- - - - MBITS  * 18  NCHAR  ■ 6 - - - - 


ARRAY 

123*5670123*5670  1 23*567oi 23*5670  l23*567oi23*567o  123*5670123*5670 
TEMPLATE  LENGTH  > 10 

0000000000123*56  0u0000000070l23*  000000000056701 2 00000000003*5670 
0000000000123*56  000000000070123*  00fl00000005o70l2  00000000003*5670 
0000000000123*56  000000000070123* 

PACKEO  LENGTH  * a EXCEEOS  Na  * * 

THE  FIRST  10  BYTES  -ILL  F>E  PROCESSED 

BRRAY  LENGTH  a a 

123*5670123*5670  123*5670123*5670  123*5670123*5670  123*5670123*0000 


- - - - MBITS  * 30  NCHAR  « 1 0 - > - - 


array 

123*5670123*5670  1 ?3*567o 1 23*5670  1 23*567>J  1 23*5670  123*5670123*5670 
TEMPLATE  LENGTH  m 6 

000000123*567012  0000003*5670123*  000000567oi23*56  00u000701 23*5670 
000000123*567012  0000003*5670123* 

PACKED  LENGTH  s 13  EXCEEDS  N A a * 

THE  FIRST  6 BYTES  -ILL  PE  PROCESSED 

BRRAY  LEnGTh  = * 

123*5670123*5670  1 ?3*567oi 23*5670  1 23* 56 70 1 2 3*567o  1 2 3*56  To  1 23*0000 


